I purposefully reengineered the history to make it possible to review the changes. Of course I will squash the commits later to eventually merge.

The two changes that might require reviewing are bac774d and cdc4442. All others are more or less boring.

Awesome! You should also add a link to it from https://github.com/lampepfl/dotty/blob/master/docs/docs/index.md, also the tex version should be deleted to avoid duplication.

The two changes that might require reviewing are bac774d and cdc4442.

@odersky, could you have a look please?

Ah, one thing I was not sure about: I deleted the tree annotations that can be found in the tex version, like

-|  Refinement                                             RefinedTypeTree(EmptyTree, refinement)
+|  Refinement

Not sure, whether you want to keep them.

Looks great. Definitely better to have this in markdown.

I would leave the tree annotations in this version of the document, though. The reason is that they give us a good overview what parsed constructs map into. When we export the document to a language spec, they would be removed, of course.

LGTM, Thanks!